<HTML><HEAD><TITLE>readvar(+Stream, -Term, -VarList)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Term I/O</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>readvar(+Stream, -Term, -VarList)</H1>
Succeeds if the next Prolog term from the input stream Stream is
successfully read and unified with Term, and any variables in Term are
collected in the list VarList, together with their names.


<DL>
<DT><EM>Stream</EM></DT>
<DD>Integer (stream number) or Atom (reserved or user-defined                symbolic stream name).
</DD>
<DT><EM>Term</EM></DT>
<DD>Prolog term.
</DD>
<DT><EM>VarList</EM></DT>
<DD>A Variable.
</DD>
</DL>
<H2>Description</H2>
   Used to read the next term from the input stream Stream, unify it with
   Term and store any variables in Term to the list VarList.  This is a
   list of pairs in the format [VarName|Var].

<P>
   VarName is the literal input variable name expressed as an atom; Var is
   the variable.  The first element of the pair Varname is the atom
   corresponding to the variable name, and the second element Var is the
   corresponding variable.

<P>
   If there is more than one Prolog term in the file, the term must be in
   Prolog term format i.e.  terminated by a period and a blank space
   character, neither of which are retained by Prolog.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>readvar(+, -, -) is semidet
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Fail Conditions</H3>
Fails if a syntax error was detected and no term could be read
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Stream is not instantiated.
<DT><EM>(5) type error </EM>
<DD>Stream is not an atom or an integer, Varlist is not a    variable.
<DT><EM>(190) end of file reached </EM>
<DD>End of file was encountered before reading any character.
<DT><EM>(192) illegal stream mode </EM>
<DD>Stream is not an input stream.
<DT><EM>(193) illegal stream specification </EM>
<DD>Stream is an illegal stream specification.
<DT><EM>(198) reading past the file end </EM>
<DD>Trying to read even after the error 190 was raised.
</DL>
<H2>Examples</H2>
<PRE>
Success:
      [eclipse]: readvar(input,Term,VarList).
      &gt; atom.
      Term = atom
      VarList = []
      yes.

      [eclipse]: readvar(input,T,L).
      &gt; X.
      T = _50
      L = [['X'|_50]]
      yes.

      [eclipse]: system('cat file1').
      f(X,Y).
      g(1,X).
      yes.
      [eclipse]: open(file1,update,r), readvar(r,T1,V1),
      &gt; readvar(r, T2,V2).
      T1 = f(_120, _122)
      V1 = [['X'|_120], ['Y'|_122]]
      T2 = g(1, _146)              % the clauses are separate,
      V2 = [['X'|_146]]            % so the X's are different.
      yes.

Fail:
      [eclipse]: readvar(input, X + 2,V).
      &gt; X + 1.
      no.

Error:
      readvar(S,a(b,c),V).          (Error 4).
      readvar("string",a(b,c),V,).  (Error 5).
      readvar(output,X + 2,V).      (Error 192).
      readvar(atom,X + 2,V).        (Error 193).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/ioterm/read-1.html">read / 1</A>, <A HREF="../../kernel/ioterm/read-2.html">read / 2</A>
</BODY></HTML>
